Skip to main content

Web — Technical Reference

This document covers the technical details for building web Aspects that integrate with the Candescent Digital Banking platform. Web Aspects are JavaScript files injected directly into the OLB DOM, with full access to the page.

For general OIDC concepts (Authorization Code Flow, ID token validation, claims, etc.), see the OIDC Integration Technical Reference.

For the mobile-specific technical reference, see Mobile Technical Reference.

User Context via Global Variables​

After a user logs in, the platform exposes session information through the dbk.sessionInfo() API. Your Aspect can read it directly from the DOM.

Available Fields​

FieldMethodDescription
User GUIDdbk.sessionInfo().userGuidUnique identifier for the logged-in user
Full Namedbk.sessionInfo().userFullNameDisplay name of the logged-in user

Example​

const guid = dbk.sessionInfo().userGuid;
const name = dbk.sessionInfo().userFullName;

console.log(`User: ${name}, GUID: ${guid}`);

Considerations​

AdvantageDisadvantage
Fast, synchronous accessData is static and globally accessible in the DOM
No backend call requiredShould not be the sole source of trust for sensitive operations
Automatically cleared on logoutPotentially readable by other scripts on the page

When to use: Display personalization, cross-validation of user-provided information (e.g., verifying identity during chat), and non-security-critical integrations.

User Context via OIDC​

For integrations that require secure, verified identity, the platform provides an Aspects-specific OIDC endpoint. This uses the standard OIDC Authorization Code Flow — your Aspect requests an authorization code from the platform, and your backend exchanges it for a token with user claims. This step is identical to the standard OIDC token exchange described in the OIDC Integration Technical Reference.

warning

Never call the Candescent API gateway directly from the front-end Aspect. The Aspect obtains the authorization code; your backend server performs the token exchange.

How It Works​

  1. The Aspect (running in the user's browser) calls the Aspects token endpoint to get an authorization code.
  2. The Aspect sends this code to your backend.
  3. Your backend exchanges the code with Candescent's token endpoint for an ID token containing user claims.
  4. Your backend uses the claims to identify the user and respond to the Aspect.

Aspects Token Endpoint​

GET https://<FI_DOMAIN>/feng-bff/beta/v1/aspect/token?clientId=<YOUR_CLIENT_ID>
ParameterDescription
FI_DOMAINThe financial institution's branded domain
YOUR_CLIENT_IDYour OIDC consumer/client identifier

Example URL:

https://online.acmebank.com/feng-bff/beta/v1/aspect/token?clientId=YOUR_CLIENT_ID

Request Details​

const CLIENT_ID = 'yourOIDCconsumerIdentifier';
const TOKEN_URL = `https://online.acmebank.com/feng-bff/beta/v1/aspect/token?clientId=${CLIENT_ID}`;

fetch(TOKEN_URL, {
  method: 'GET',
  headers: {
    'correlationId': crypto.randomUUID(),
    'Cookie': document.cookie,
    'Accept': 'application/json'
  }
})
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP status code: ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    // Send data.token to your backend for exchange
    console.log('Authorization code received. Send to backend for token exchange.');
  })
  .catch(error => {
    console.error(`Error fetching authorization code: ${error.message}`);
  });

Backend Token Exchange​

Once your backend receives the authorization code, it exchanges it with the centralized Candescent token endpoint. This step is identical to the standard OIDC token exchange described in the OIDC Integration Technical Reference.

Token endpoint:

  • Stage: https://api.candescent.com/digitalbanking/stage/oauth2/v1/token
  • Production: https://api.candescent.com/digitalbanking/prd/oauth2/v1/token

For full details on token exchange requests, ID token validation, and supported claims, see the OIDC Technical Reference.

Web-Specific utilities​

Web Aspects have access to the following platform-provided utilities:

dbk.sessionInfo()​

Returns user session data as described above. Available only after the user has logged in.

dbk.loadScript(url)​

Loads an external JavaScript file asynchronously and returns a Promise that resolves when the script is loaded. Use this to load third-party SDKs.

dbk.loadScript('https://cdn.your-vendor.com/sdk/v3/widget.js').then(function () {
  // Vendor SDK is now available
});

Security Best Practices​

  • Never expose tokens in the front-end. The Aspect receives an authorization code, not a token. Your backend performs the token exchange.
  • Use HTTPS for all communication.
  • Validate tokens on your backend using the JWKS file provided by your Candescent PM. See ID Token Validation.
  • Global variable data (dbk.sessionInfo()) should be used for display or cross-validation only — not as a trusted identity source for sensitive operations.

Next Steps​